Substrates 2026 - Proceedings

Summary

The submission is about a web-based substrate called HyperDoc. In HyperDoc, traditional ways of documenting knowledge, such as text and pictures, can be freely combined with code and dynamically created visualizations. Unlike systems like Jupyter notebooks, which use a linear cell-based structure, HyperDoc is structured as pages. The submission includes a link to an interactive demo, the system's overall goals, and core implementation decisions.

Strengths

How people collect, visualize, and share knowledge is a very interesting topic and very fitting for malleable systems such as substrates.

As a presentation of a substrate system, the submission matches the workshop's call for contributions very well.

I like that there is not "just" a screenshot (or similar) of the system, but a link to a demo.

As I am very interested in the usability of systems, I like that the author included some insights on how they envision the system to be used. For instance, I liked the focus on compatibility with existing workflows.

While trying the demo, I liked that there were some prepared examples with, e.g., code-generated diagrams and executable code cells. It is also useful to view multiple open pages at once, allowing you to view related pages together. All pages consist of multiple tabs, for example, to switch to the source, but tabs can also include additional information, e.g., on the author(s).

Questions and Suggestions

A question regarding demo: Is it view-only or can it be edited? The playground seems to be intentionally disabled, but I also found no way to edit the source/code snippets.

How much can I change when using the system? Is it mainly intended for content authoring, or can I also edit, for instance, the UI? (e.g., font size, coloring, maybe even complicated edits like adding some sort of special screenreader support)

The submission touches on this a bit. Still, I think that in further discussions/publications, it could be interesting to explore how the core design decisions for this system differ from those of other online authoring systems. Some systems I would personally find interesting:

general-purpose web-IDEs, e.g., Lively (or even the GitHub/GitLab web interfaces)

very specific web-IDEs, e.g., the game engine Construct or online versions of table programming environments (like Google Sheets)

a comparison to the concept of active essays in general (e.g., Active Essays on the Web (https://doi.org/10.1109/C5.2009.10), but I think a lot of gamified learning platforms like brilliant.org could also be argued to be active essays.)

Configurable knowledge hubs, e.g., Notion

Jupyter, including research prototypes that deviate from the linear cell design

Giving more examples on the intended audience could also be helpful. Is this mainly for research knowledge bases? Or is, for instance, a little fan-curated wiki for a TV show also an intended use case?

Is there a concept of versioning that is public to the viewer? In existing knowledge systems like Wikipedia and Confluence, it is helpful to view edit history and even subscribe to change notifications for especially important pages. (Also, the submission mentions that the system encourages fork-and-adapt: Is it a git-style fork, as in changes to the original can be patched to the fork if wanted? Or is it a copy?)

Small thing: Adding a URL to reference 3 would be helpful. I think this is one of Bret Victor's blog posts, but he did so many posts and demos that there could be mix-ups.

I appreciated the clear articulation of HyperDoc’s goals and implementation strategy, which made more sense after I had explored the interface somewhat. One issue that is raised for me right away is that whilst the choice of Common Lisp as an implementation substrate is well motivated in terms of its support for introspection and long-term stability, the fact that code is surfaced as a first-class citizen in the resulting hypermedia system implies that this is a substrate choice that cannot be straightforwardly hidden during the process of use. This challenges widespread literacies amongst typical user communities.

The author is well aware of the technical and practical terrain surrounding their implementation and the HyperDoc interface helpfully chooses a widely reproduced worked example from the transparent science literature, a notebook analyzing the outbreak of influenza epidemics. This is very helpful in comparing the literacy and portability profile of the resulting artefacts. This reviewer has the misfortune to be deeply involved in the maintenance of data processing pipelines written in R, and it is entirely unarguable that Common Lisp is a massively better architected, documented and stable basis for computational literacy than R. Unfortunately, R is the only computational literacy that my target community, naturalists and biologists, are exposed to in their standard education which immediately settles the argument in favour of it. These kinds of pragmatics sadly should not be underestimated, and I find that they often are by those promoting new kinds of notations and substrates --- that insufficient attention is given to the existing literacies and artefact ecologies where users want computation manifested to them.

In this regard, HyperDoc recognises that the web is a primary site where users will demand computation to manifest, and has a well-crafted, tastefully laid out web interface in which I wasn’t easily able to provoke any obvious interaction bugs (although I was occasionally able to make the interface “jam” by some interactions, requiring the page to be reloaded) - this is no mean achievement and represents an admirable implementation effort. I do find, however, that its web idiom falls into a similar of other interesting substrates such as Gilad Bracha’s Ampleforth - it is a “translation project” in that the primitives of a foreign computational system are translated into particularised web widgets by a largely unidirectional process. More difficult is what to me would be the more attractive “compatibilism” proposed by other members of the community such as Joel Jakubovic, and Stephen Kell’s “integration domains” where the native primitives of the web can coexist on a first-class footing alongside those of the substrate.

The general idiom of “enclosing the primitives of the web” rather than exposing them or living alongside them also continues in the interface paradigm itself. The multi-panel interface, extending to the right, reproduces a literacy that the user will already be familiar with - that of tabbed browsing - and may well puzzle them interactionally on how they now seem to have a “browser within a browser”. A similar “enclosure” happens when one navigates to a Wikipedia page - rather than getting to the natively rendered version of the page, one instead gets a captured one, without the familiar framing and navigation, and some interactional possibilities stripped out.

I’m aware that these are simply manifestations of the particular “browser” which is being demonstrated here and that another browser could make different implementation choices once “HyperDoc as a protocol” is implemented - but it is not clear how this implementation factoring could abstract away the underlying computational model, if a basis in Common Lisp has been a fundamental architectural choice.

I like what I can apprehend of the factoring of the HyperDoc system, and the fact that it is designed to allow multiple “browsers” to present interfaces to the same structures. It’s possible that this could remedy the interactional issues I mention but I don’t see how it could get beyond the fundamental dynamic of enclosure.

In terms of the interface affordances themselves, what I would have liked to see is a more natural and deeper inspectability of the interface which hopefully is assisted by the substrate’s primitives. For example, the HyperDoc self-documentation explains that an Alt-click interaction is sometimes available on some elements in order to determine what function they will have and what data they consume - however this seems to be available on only a limited range of elements, seemingly small-snippets of inline code or buttons. Trying to investigate the main graph of Influenze-Like Illness epidemics only gets one access to a snippet reading

<view-transclusion>
(👀strongest-epidemics *data*)
</view-transclusion>

with no apparent affordances to determine how to navigate to the other end of the transclusion site to see how one could influence the resulting plot, and also why and how the “strongest-epidemics” target might be in scope from the transcluding location.

The resulting system is admirable, but I feel suffers from poor “disclosability” - it’s hard to see how the artefacts presented in it could manifest themselves separately from the computational system which supports them.

The “enclosure” process I feel extends to the notebook ecology itself which the HyperDoc system is intimately part of - the peer systems that it positions itself alongside are systems such as Jupyter and Rmarkdown notebooks which are admirable in their way for certain kinds of work, but are receiving a critique (e.g. from this 2020 CHI paper) as venues which rule out a certain kind of work from being done. For example, my work in the R community couldn’t effectively be done within the notebook idiom, since it requires processing of large datasets with fragile, interactional algorithms which need to be supervised fairly closely, and then published as web pages that are either completely generic and free-standing, or hosted in other kinds of enclosed systems such as WordPress or WiX sites.

I think HyperDoc is a great initiative which deserves to be supported, and I invite the author to consider whether their audience could be served by loosening some of its computational and interactional dependencies. I’ve learned a lot from studying it, and I think it will provoke a deal of very illuminating discussions at the workshop.

Review 2
PC member	Joel Jakubovic
Overall evaluation	This submission describes the background and strategy for HyperDoc, a hypermedia substrate aimed at knowledge workers that supports code - in particular, its own, in a reflective manner. To understand the subject matter, I spent a few minutes in the linked demo. I find the system itself and this submission to be welcome contributions to this year's workshop. I find the the project's central idea of "code as a representation of knowledge" interesting yet mysterious. I would like to see more elaboration of what the author means by this. For example, I am partial to the view that code is "executable philosophy" - the need to implement one's ideas on a glorified calculator necessarily forces a disciplined reductionism that is absent in philosophy. If my straw philosopher proclaims that "thinking" equals "deliberating" plus "comprehending", appearing to have broken it down into smaller components, trying to implement this in code shows us how little it's solved the problem: our function think() consists of deliberate() and comprehend(), both of which still remain to be defined, and appear to be no less mysterious than the original think(). So when we succeed at implementing something - an example I like to use is a text layout algorithm - we've necessarily embedded formerly implicit knowledge about the problem domain, eg "text flows left to right and top to bottom", "the x axis points left to right and the y points top to bottom", "words are solid objects that don't overlap", "spaces are somewhat flexible", "despite being solid, words are breakable at certain hyphenation points". So I sort of get how code is a representation of domain knowledge - but I've no idea if this is what the author has in mind. I've always found it much easier to see data structures, class hierarchies etc. as a representation of knowledge. They're usually crude approximations of "is-a", "has-a" type relationships, but maybe Lisp and the GOFAI tradition had more sophisticated representations - there's still a lot for me to learn about Lisp. Put it this way: code is a representation of knowledge - as opposed to what? In the submission, it's contrasted with "a medium for making information processing tools". Okay. Are these two views just different ways that any code can be read, or is "knowledge" code clearly distinguishable from "code as a toolmaking medium" by some telltale signs? In HyperDoc's own documentation, Bret Victor's "Explorable Explanations" is cited as inspiration. Is the idea that knowledge workers will build executable models of their arguments or hypotheses, and that's how the code is a representation of their knowledge? Other comments: "Hypermedia systems are traditionally limited to passive media" - is this so? HyperCard surely had dynamic media via the HyperTalk language. Is that just the exception that proves the rule? I'm reminded of Alan Kay's disappointments with the Web - chiefly that it didn't come with its own authoring tool (Notepad doesn't hold a candle to HyperCard). But he also said somewhere (my wording) that it's an outrage that the code samples in a Wikipedia article aren't runnable, or if they are it's by polyfilling functionality that a rich hypermedia system ought to already have built-in. Consider the following view that I think is representative of Kay's school: the purpose of a hypermedia system is to support the safe, sandboxed execution of arbitrary programs from untrusted sources. Of course, this is just what the modern web browser has evolved into (although it certainly wasn't safe and secure for much of its history!) Does HyperDoc agree / disagree with this telos for hypermedia? "Code as database: hyperlinks to functions and classes by name" - what immediately leapt to mind when I read this was the age-old problem of distinguishing identity from location. Are broken links permitted in HyperDoc? Any plans for refactoring operations which try to avoid dangling references? I assume the names have to be fully qualified by library / author / something to reduce collisions? "The long-term vision for HyperDoc is an implementation as a protocol" - this paragraph compels me to plug my Smalltix project: Smalltalk objects are directories and methods are executable files (but it hasn't gone as far as a network protocol). I'm quite a fan of this extreme loose coupling and "mixing different implementation technologies". I would like to know more about why the protocol would be a major challenge and why a lower-level substrate would be needed. This also raises the question of what the "commitment surface" is for users; i.e. what technologies or practices they have to commit to in order to author in the system. Currently it's something like "they must be able to program in Lisp" - the impl-as-protocol vision would require fewer commitments from users (essentially, you commit to a protocol, and that's it?). I do appreciate that the current focus is on "consulting" hypermedia rather than authoring it - but again this makes me wonder what exactly "consulting and exploring code-as-knowledge" consists of. I look forward to finding out more at the workshop!

Review 3
PC member	Chee Rabbits
Overall evaluation	i initially read this on a train on a piece of printed paper, so the on-line demo was not particular self-explanatory to me. i think it would be nice to also include a description of the system in the paper. i believe it would also help draw more tight lines between the implementation and the motivations. later, i opened up the on-line demo and found that it was still not self-explanatory. i did not know where to click and many places that seemed clickable did not reward me upon clicking. i liked the high value on code transparency in opposition to software engineering principals. personally i believe that a truly valuable substrate will have no hidden state whatsoever, everything being represented in some form on the screen the sentence "to a practicing knowledge worker, adopting HyperDoc should feel like integrating like integrating a new software library into their workflow rather than like switching to a new programming language" intriguing. i would like to hear more about what those feel like, and how they are distinguished. do knowledge workers often do these things? i found the argument for using common lisp + clog unsatisfying. though i love common lisp very much and use it often. i think the strong argument in the paper itself about not using a language that separates binary executables from their source code can equally be applied to putting any distance between implementation and execution environment at all. perhaps i've misunderstood something about how common lisp and clog are used in the environment, but it feels like javascript would fit the bill better in this instance. but, who knows. maybe this is just vibes. the very last paragram has a section about collaboration across three time scales. paraphrased: 1. real time collab 2. offline collab 3. long-term community-scale collab i love this^

Review 4
PC member	Stephen Kell
Overall evaluation	This is an intriguing system, and the focus on the knowledge-worker audience is welcome. I think it will be an excellent addition to the workshop programme. Below I pose a few questions and comments in response to the demo and paper, which may (or may not!) be useful when thinking of the workshop presentation. "To a practicing knowledge worker, adopting HyperDoc should feel like integrating a new software library into their workflow, rather than like switching to a new programming language or a new development toolbox" ... this is a great aspiration but my feel from the demo leaned still towards the latter (new language/toolbox). What remains to be done to make it the former? I am guessing this is tied up with "implementation as a protocol". Meanwhile the preference for "fork-and-adapt" rather than "adopt-a-dependency" is a good fit in many cases, especially with scientists being scientists... but might there be a need to support both, especially once a single hyperbook becomes too large? Relatedly, is the protocol just about separating inspector from data, or would it also allow the data to be distributed? I suspect the latter amounts to some support for the adopt-a-dependency model. It's "obvious" in a sense, but code already "is" hypertext, in the sense that it is dense with formally bound interreference. This got me thinking, albeit without any complete thoughts thus far, about the overlaps between hypertext and coding environments generally. In the paper we read that "other interactive programming systems, such as Smalltalk or Python, lack the stability required by the life cycle of collective knowledge, which evolves on a time scale measured in decades". It's nn intriguing statement... still I was left wondering whether this is an intrinsic property of those systems, or just the kind sof tasks they have mainly been used for. E.g. if we tried to realise a Hyperbook directly in the medium of a Smalltalk-80 image, what would and wouldn't work? typos etc.: p2 "bridges" p3 "progrmaming"

Review 5
PC member	Antranig Basman
Overall evaluation	I appreciated the clear articulation of HyperDoc’s goals and implementation strategy, which made more sense after I had explored the interface somewhat. One issue that is raised for me right away is that whilst the choice of Common Lisp as an implementation substrate is well motivated in terms of its support for introspection and long-term stability, the fact that code is surfaced as a first-class citizen in the resulting hypermedia system implies that this is a substrate choice that cannot be straightforwardly hidden during the process of use. This challenges widespread literacies amongst typical user communities. The author is well aware of the technical and practical terrain surrounding their implementation and the HyperDoc interface helpfully chooses a widely reproduced worked example from the transparent science literature, a notebook analyzing the outbreak of influenza epidemics. This is very helpful in comparing the literacy and portability profile of the resulting artefacts. This reviewer has the misfortune to be deeply involved in the maintenance of data processing pipelines written in R, and it is entirely unarguable that Common Lisp is a massively better architected, documented and stable basis for computational literacy than R. Unfortunately, R is the only computational literacy that my target community, naturalists and biologists, are exposed to in their standard education which immediately settles the argument in favour of it. These kinds of pragmatics sadly should not be underestimated, and I find that they often are by those promoting new kinds of notations and substrates --- that insufficient attention is given to the existing literacies and artefact ecologies where users want computation manifested to them. In this regard, HyperDoc recognises that the web is a primary site where users will demand computation to manifest, and has a well-crafted, tastefully laid out web interface in which I wasn’t easily able to provoke any obvious interaction bugs (although I was occasionally able to make the interface “jam” by some interactions, requiring the page to be reloaded) - this is no mean achievement and represents an admirable implementation effort. I do find, however, that its web idiom falls into a similar of other interesting substrates such as Gilad Bracha’s Ampleforth - it is a “translation project” in that the primitives of a foreign computational system are translated into particularised web widgets by a largely unidirectional process. More difficult is what to me would be the more attractive “compatibilism” proposed by other members of the community such as Joel Jakubovic, and Stephen Kell’s “integration domains” where the native primitives of the web can coexist on a first-class footing alongside those of the substrate. The general idiom of “enclosing the primitives of the web” rather than exposing them or living alongside them also continues in the interface paradigm itself. The multi-panel interface, extending to the right, reproduces a literacy that the user will already be familiar with - that of tabbed browsing - and may well puzzle them interactionally on how they now seem to have a “browser within a browser”. A similar “enclosure” happens when one navigates to a Wikipedia page - rather than getting to the natively rendered version of the page, one instead gets a captured one, without the familiar framing and navigation, and some interactional possibilities stripped out. I’m aware that these are simply manifestations of the particular “browser” which is being demonstrated here and that another browser could make different implementation choices once “HyperDoc as a protocol” is implemented - but it is not clear how this implementation factoring could abstract away the underlying computational model, if a basis in Common Lisp has been a fundamental architectural choice. I like what I can apprehend of the factoring of the HyperDoc system, and the fact that it is designed to allow multiple “browsers” to present interfaces to the same structures. It’s possible that this could remedy the interactional issues I mention but I don’t see how it could get beyond the fundamental dynamic of enclosure. In terms of the interface affordances themselves, what I would have liked to see is a more natural and deeper inspectability of the interface which hopefully is assisted by the substrate’s primitives. For example, the HyperDoc self-documentation explains that an Alt-click interaction is sometimes available on some elements in order to determine what function they will have and what data they consume - however this seems to be available on only a limited range of elements, seemingly small-snippets of inline code or buttons. Trying to investigate the main graph of Influenze-Like Illness epidemics only gets one access to a snippet reading <view-transclusion> (👀strongest-epidemics data) </view-transclusion> with no apparent affordances to determine how to navigate to the other end of the transclusion site to see how one could influence the resulting plot, and also why and how the “strongest-epidemics” target might be in scope from the transcluding location. The resulting system is admirable, but I feel suffers from poor “disclosability” - it’s hard to see how the artefacts presented in it could manifest themselves separately from the computational system which supports them. The “enclosure” process I feel extends to the notebook ecology itself which the HyperDoc system is intimately part of - the peer systems that it positions itself alongside are systems such as Jupyter and Rmarkdown notebooks which are admirable in their way for certain kinds of work, but are receiving a critique (e.g. from this 2020 CHI paper) as venues which rule out a certain kind of work from being done. For example, my work in the R community couldn’t effectively be done within the notebook idiom, since it requires processing of large datasets with fragile, interactional algorithms which need to be supervised fairly closely, and then published as web pages that are either completely generic and free-standing, or hosted in other kinds of enclosed systems such as WordPress or WiX sites. I think HyperDoc is a great initiative which deserves to be supported, and I invite the author to consider whether their audience could be served by loosening some of its computational and interactional dependencies. I’ve learned a lot from studying it, and I think it will provoke a deal of very illuminating discussions at the workshop.

Reviews for Paper 4: HyperDoc - a hypermedia substrate for knowledge workers

Summary

Strengths

Questions and Suggestions